### RSIB Interface Functions

This section lists all functions of the DLL "RSIB.DLL" or "RSIB32.DLL" or "librsib.so", which allow to produce control applications.

- Variables

- Interface Functions

#### Variables ibsta
, iberr
, ibcntl

Same as with the National Instruments interface, successful execution of a command can be checked by means of the variables ibsta, iberr and ibcntl. To this end, references to the three variables are transferred to all RSIB functions. In addition, the status word ibsta is returned as a function value by all functions.

##### Status word ibsta

All functions send back a status word that provides information on the status of the RSIB interface. The following bits are defined:

Bit name | Bit | Hex code | Description
ERR | 15 | 8000 | This bit is set if an error occurs during a function call. If this bit is set, iberr contains an error code which specifies the error.
TIMO | 14 | 4000 | This bit is set if a timeout occurs during a function call. A timeout may occur in the following situations: while waiting for an SRQ with the function RSDLLWaitSrq(). if no acknowledgment is received for data sent to an instrument with RSDLLibwrt() or RSDLLilwrt(). if no response from server to a data request with function RSDLLibrd() or RSDLLilrd().
CMPL | 8 | 0100 | This bit is set if the reply of the IEC/IEEE-bus parser is completely read. If a reply of the parser is read with the function RSDLLilrd() and the buffer length is not sufficient, the bit is cleared.

#### Error variable iberr

If the ERR bit (8000h) is set in the status word, iberr contains an error code that specifies the error. The RSIB has error codes of its own independent of the National Instrument interface.

Error | Error code | Description
IBERR_DEVICE_REGISTER | 1 | RSIB.DLL cannot register any new device.
IBERR_CONNECT | 2 | Link to the device has failed.
IBERR_NO_DEVICE | 3 | An interface function was called with an invalid device handle.
IBERR_MEM | 4 | No free memory available.
IBERR_TIMEOUT | 5 | Timeout has occurred.
IBERR_BUSY | 6 | The RSIB interface is blocked by a function not yet completed. Windows is not blocked, for example, by function RSDLLibrd() if data is still to be transmitted in response to this function. In this case a new call is possible. Further calls are however rejected by RSIB.DLL with error code IBERR_BUSY.
IBERR_FILE | 7 | Error in reading from or writing to a file.
IBERR_SEMA | 8 | Error upon creating or assigning a semaphore (only under Unix)

#### Count variable - ibcntl

The variable ibcntl is updated with the number of bytes transmitted on every read and write function call.

#### Overview of Interface Functions

The library functions are adapted to the interface functions of National Instruments for GPIB programming. The functions supported by the libraries are listed in the following table.

Function | Description
RSDLLibfind() | Provides a handle for access to a device.
RSDLLibwrt() | Sends a zero-terminated string to a device.
RSDLLilwrt() | Sends a certain number of bytes to a device.
RSDLLibwrtf() | Sends the contents of a file to a device.
RSDLLibrd() | Reads data from a device into a string.
RSDLLilrd() | Reads a certain number of bytes from a device.
RSDLLibrdf() | Reads data from a device into a file.
RSDLLibtmo() | Sets timeout for RSIB functions
RSDLLibsre() | Switches a device into the local or remote state
RSDLLibloc() | Temporarily switches a device into the local state
RSDLLibeot() | Enables/disables the END message for write operations.
RSDLLibrsp() | Performs a serial poll and provides the status byte.
RSDLLibclr | Sends the command SDC (Device Clear) to the instrument.
RSDLLibonl() | Sets the device On/Offlline.
RSDLLTestSrq() | Checks whether a device has generated an SRQ.
RSDLLWaitSrq() | Waits until a device generates an SRQ.
RSDLLSwapBytes | Swaps the byte sequence for binary numeric display (only required for non-Intel platforms)

### Description of Interface Functions

#### RSDLLibfind()

The function provides a handle for access to the device with the name udName.

VB format: Function RSDLLibfind (ByVal udName$, ibsta%, iberr%, ibcntl&) As Integer

C-format: short WINAPI RSDLLibfind( char far *udName, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLibfind( char *udName, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: udName IP address of device

Example: ud = RSDLLibfind ("89.10.38.97", ibsta, iberr, ibcntl)

The function must be called prior to all other functions of the interface.

As return value, the function provides a handle that must be indicated in all functions for access to the device. If the device with the name udName is not found, the handle has a negative value.

#### RSDLLibwrt

This function sends data to the device with the handle ud.

VB format: Function RSDLLibwrt (ByVal ud%, ByVal Wrt$, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibwrt( short ud, char far *Wrt, short far *ibsta, short far *iberr, unsigned long far *ibcntl )

C format (Unix): short RSDLLibwrt( short ud, char *Wrt, short *ibsta, short *iberr, unsigned long *ibcntl )

Parameter: ud Device handle

Wrt String sent to the device.

Example: RSDLLibwrt(ud, "SENS:FREQ:STAR?", ibsta, iberr, ibcntl)

This function allows to send setting and query commands to the measuring instruments. Whether the data is interpreted as a complete command can be set using the function RSDLLibeot().

#### RSDLLilwrt

This function sends Cnt bytes to a device with the handle ud.

VB format: Function RSDLLilwrt (ByVal ud%, ByVal Wrt$, ByVal Cnt&, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLilwrt( short ud, char far *Wrt,
unsigned long Cnt, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLilwrt( short ud, char *Wrt, unsigned long Cnt, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle

Wrt String sent to the GPIB parser.

Cnt Number of bytes sent to the device.

Example: RSDLLilwrt (ud, '......', 100, ibsta, iberr, ibcntl)

Like RSDLLibwrt() this function sends data to a device. The only difference is that binary data can be sent as well. The length of the data is not determined by a zero-terminated string, but by the indication of Cnt bytes. If the data is to be terminated with EOS (0Ah), the EOS byte must be appended to the string.

#### RSDLLibwrtf

This function sends the contents of a file file$ to the device with the handle ud.

VB format: Function RSDLLibwrtf (ByVal ud%, ByVal file$, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibwrt( short ud, char far *Wrt, short far *ibsta, short far *iberr, unsigned long far *ibcntl )

C format (Unix): short RSDLLibwrt( short ud, char *Wrt, short *ibsta, short *iberr, unsigned long *ibcntl )

Parameter: ud Device handle

file File the contents of which are sent to the device.

Example: RSDLLibwrtf(ud, "C:\db.sav", ibsta, iberr, ibcntl)

This function allows to send setting and query commands to the measuring instruments. Whether the data is interpreted as complete command can be set using the function RSDLLibeot().

#### RSDLLibrd()

The function reads data from the device with the handle ud into the string Rd.

VB format: Function RSDLLibrd (ByVal ud%, ByVal Rd$, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibrd( short ud, char far *Rd, short far *ibsta, short far *iberr, unsigned long far *ibcntl )

C format (Unix): short RSDLLibrd( short ud, char *Rd, short *ibsta, short *iberr, unsigned long *ibcntl )

Parameter: ud Device handle

Rd String into which the read data is copied.

Example: RSDLLibrd (ud, Rd, ibsta, iberr, ibcntl)

This function fetches the responses of the GPIB parser to a query.

In the case of Visual Basic programming, a string of sufficient length must be generated before. This can be done during the definition of the string or using the command Space$().

Generation of a string of the length 100: - Dim Rd as String * 100

- Dim Rd as String

Rd = Space$(100)

#### RSDLLilrd

This function reads Cnt bytes from the device with the handle ud.

VB format: Function RSDLLilrd (ByVal ud%, ByVal Rd$, ByVal Cnt&, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLilrd( short ud, char far *Rd, unsigned long Cnt, short far *ibsta, short far *iberr, unsigned long far *ibcntl )

C format (Unix): short RSDLLilrd( short ud, char *Rd, unsigned long Cnt, short *ibsta, short *iberr, unsigned long *ibcntl )

Parameter: ud Device handle

cnt Maximum number of bytes copied from the DLL into the target string Rd.

Example: RSDLLilrd (ud, RD, 100, ibsta, iberr, ibcntl)

Like the function RSDLLibrd(), this function reads data from a device. The only difference is that in this case the maximum number of bytes to be copied into the target string Rd can be indicated by means of Cnt. This function prevents writing beyond the end of the string.

#### RSDLLibrdf()

Reads data from the device with the handle ud into the file file.

VB format: Function RSDLLibrdf (ByVal ud%, ByVal file$, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibrd( short ud, char far *file, short far *ibsta, short far *iberr, unsigned long far *ibcntl )

C format (Unix): short RSDLLibrd( short ud, char *file, short *ibsta, short *iberr, unsigned long *ibcntl )

Parameter: ud Device handle

file File into which the read data is written.

Example: RSDLLibrdf (ud, "c:\db.sav", ibsta, iberr, ibcntl)

The file name may as well include a drive or path specification.

#### RSDLLibtmo

This function defines the timeout for a device. The default value for the timeout is set to 5 seconds.

VB format: Function RSDLLibtmo (ByVal ud%, ByVal tmo%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibtmo( short ud, short tmo, short far *ibsta, short far *iberr, unsigned long far *ibcntl )

C format (Unix): short RSDLLibtmo( short ud, short tmo, short *ibsta, short *iberr, unsigned long *ibcntl )

Parameter: ud Device handle

tmo Timeout in seconds

Example: RSDLLibtmo (ud, 10, ibsta, iberr, ibcntl)

#### RSDLLibsre

This function sets the device to the 'LOCAL' or 'REMOTE' state.

VB format: Function RSDLLibsre (ByVal ud%, ByVal v%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibsre( short ud, short v, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLibsre( short ud, short v, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle

v State of device

0 - local

1 - remote

Example: RSDLLibsre (ud, 0, ibsta, iberr, ibcntl)

#### RSDLLibloc

This function temporarily switches the device to the 'LOCAL' state.

VB format: Function RSDLLibloc (ByVal ud%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibloc( short ud, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLibloc( short ud, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle

Example: RSDLLibloc (ud, ibsta, iberr, ibcntl)

After switchover to LOCAL state, the instrument can be manually operated via the GUI. On the next access to the instrument by means of one of the functions of the library the instrument is switched again to the REMOTE state.

#### RSDLLibeot

This function enables or disables the END message after write operations.

VB format: Function RSDLLibeot (ByVal ud%, ByVal v%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibsre( short ud, short v, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLibsre( short ud, short v, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle.

v 0 - no END message

1 – send END message

Example: RSDLLibeot (ud, 1, ibsta, iberr, ibcntl)

If the END message is disabled, the data of a command can be sent with several successive calls of write functions. The END message must be enabled again before sending the last data block.

#### RSDLLibrsp

This function performs a serial poll and provides the status byte of the device.

VB format: Function RSDLLibrsp(ByVal ud%, spr%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibrsp( short ud, char far* spr, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLibrsp( short ud, char *spr, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle

spr Pointer to status byte

Example: RSDLLibrsp(ud, spr, ibsta, iberr, ibcntl)

#### RSDLLibclr

Sends the command SDC (Device Clear) to the instrument.

VB format: Function RSDLLibclr(ByVal ud%, spr%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibclr( short ud, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLibclr( short ud, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle

Example: RSDLLibclr(ud, ibsta, iberr, ibcntl)

#### RSDLLibonl

This function switches the device to 'online' or 'offline' mode. When it is switched to ‘offline’ mode, the interface is released and the device handle becomes invalid. By calling RSDLLibfind again, the communication is set up again.

VB format: Function RSDLLibonl (ByVal ud%, ByVal v%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLibonl( short ud, short v, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format: short RSDLLibonl( short ud, short v, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle

v Device state

0 - local

1 - remote

Example: RSDLLibonl(ud, 0, ibsta, iberr, ibcntl)

#### RSDLLTestSRQ

This function checks the status of the SRQ bit.

VB format: Function RSDLLTestSrq (ByVal ud%, Result%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLTestSrq( short ud, short far *result, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLTestSrq( short ud, short *result, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle

result Reference to an integer value in which the library returns the status of the SRQ bit.

0 - no SRQ

1 - SRQ active, device requests service

Example: RSDLLTestSrq (ud, result%, ibsta, iberr, ibcntl)

This function corresponds to the function RSDLLWaitSrq. The only difference is that RSDLLTestSRQ immediately returns the current status of the SRQ bit, whereas RSDLLWaitSrq waits for an SRQ to occur.

#### RSDLLWaitSrq

This function waits until the device triggers an SRQ with the handle ud.

VB format: Function RSDLLWaitSrq (ByVal ud%, Result%, ibsta%, iberr%, ibcntl&) As Integer

C format: short WINAPI RSDLLWaitSrq( short ud, short far *result, short far *ibsta, short far *iberr, unsigned long far *ibcntl)

C format (Unix): short RSDLLWaitSrq( short ud, short *result, short *ibsta, short *iberr, unsigned long *ibcntl)

Parameter: ud Device handle

result Reference to an integer value in which the library returns the status of the SRQ bit.

0 - No SRQ has occurred during the timeout

1 - SRQ has occurred during the timeout

Beispiel: RSDLLWaitSrq( ud, result, ibsta, iberr, ibcntl );

The function waits until one of the following two events occurs.

The measuring instrument triggers an SRQ

No SRQ occurs during the timeout defined with RSDLLibtmo()

#### RSDLLSwapBytes

This function changes the display of binary numbers on non-Intel platforms.

VB format: Not provided at present since it is required only on non-Intel platforms.

C format: void WINAPI RSDLLSwapBytes( void far *pArray, const long size, const long count)

C format (Unix): void RSDLLSwapBytes( void *pArray, const long size, const long count)

Parameter: pArray Array in which modifications are made

size Size of a single element in pArray

count Number of elements in pArray

Example: RSDLLSwapBytes( Buffer, sizeof(float), ibcntl/sizeof(float))

This function swaps the display of various elements from Big Endian to Little Endian and vice versa. It is expected that a coherent storage area of elements of the same file type (size byte) is transferred to pArray. This function has no effect on Intel platforms.

Different types of processor architecture store data in different byte sequences. For example, Intel processors store data in the reverse order of Motorola processors. Comparison of byte sequences:

Byte sequence | Use in | Display in memory | Description
Big Endian | Motorola processors, network standard | Most significant byte at least significant address | The most significant byte is at the left end of the word.
Little Endian | Intel processors | Least significant byte at least significant address | The most significant byte is at the right end of the word.